\documentclass{article}

\usepackage{verbatim}
\usepackage{graphicx}

\usepackage{alltt, parskip, fancyhdr, boxedminipage}


\usepackage{vmargin}
%% \setmarginsrb{leftmargin}{topmargin}{rightmargin}{bottommargin}%
%%              {headheight}{headsep}{footheight}{footskip}
\setmarginsrb{20mm}{20mm}{20mm}{20mm}
             {0pt}{0mm}{12pt}{10mm}

\usepackage{color}

\usepackage{listings}
\lstset{
language=Octave,                % choose the language of the code
basicstyle=\footnotesize,       % the size of the fonts that are used for the code
%numbers=left,                  % where to put the line-numbers
numberstyle=\footnotesize,      % the size of the fonts that are used for the line-numbers
stepnumber=2,                   % the step between two line-numbers. If it's 1 each line 
                                % will be numbered
numbersep=5pt,                  % how far the line-numbers are from the code
backgroundcolor=\color{cyan},   % choose the background color. You must add \usepackage{color}
showspaces=false,               % show spaces adding particular underscores
showstringspaces=false,         % underline spaces within strings
showtabs=false,                 % show tabs within strings adding particular underscores
frame=single,	                % adds a frame around the code
tabsize=2,	                % sets default tabsize to 2 spaces
captionpos=b,                   % sets the caption-position to bottom
breaklines=true,                % sets automatic line breaking
breakatwhitespace=false,        % sets if automatic breaks should only happen at whitespace
%title=\lstname,                 % show the filename of files included with \lstinputlisting;
%                                % also try caption instead of title
escapeinside={\%*}{*)},         % if you want to add a comment within your code
morekeywords={*,...}            % if you want to add more keywords to the set
}

\setlength{\parindent}{0pt}

\newlength{\funcindent}
\newlength{\funcwidth}
\setlength{\funcindent}{1cm}
\setlength{\funcwidth}{\textwidth}


\title{Music21(VP): an implementation the viewpoint method}




\begin{document}
\maketitle{}

\section{Use Case 01: use and create simple viewpoints}

First, import \verb&music21&:

\lstinputlisting[firstline=8,lastline=9]{usecase_01_for_tex.py}

And a chorale to work with:

\lstinputlisting[firstline=11,lastline=12]{usecase_01_for_tex.py}

Import viewpoints and constructors and get a list of predefined viewpoints:

\lstinputlisting[firstline=14,lastline=15]{usecase_01_for_tex.py}

\lstinputlisting[firstline=18,lastline=18]{usecase_01_for_tex.py}

You get this output:

\begin{lstlisting}[backgroundcolor=\color{yellow}]
predefined viewpoints:
* DurationVP               	Note --> Duration: returns the duration of a note.
* PitchVP                  	Note --> Pitch: returns the pitch of a note.
* UserVP                   	A class to facilitate the creation of user-defined VP.

viepoint constructors:
* LinkedVP                 	[VP] --> VP: Takes a list of VP and returns a VP that applies 
                                         all VP in the list, returning a list of values
\end{lstlisting}

You can \textit{demo} a viewpoint on a \textit{segment} of the chorale \verb&sBach&:

\lstinputlisting[firstline=21,lastline=22]{usecase_01_for_tex.py}

This returns the following scores (saved in MusicXML by \verb&music21& and displayed here by MuseScore):

\begin{center}
          \includegraphics[width=0.8\textwidth]{./screenshot1.eps}\\
\end{center}

Same thing for the duration viewpoint:

\begin{center}
          \includegraphics[width=0.8\textwidth]{./screenshot2.eps}\\
\end{center}

Creating a new viewpoint:

\lstinputlisting[firstline=24,lastline=27]{usecase_01_for_tex.py}

The argument \verb&[PitchVP(),PitchVP()]& is the \textit{template} expression.  It means the viewpoint will iterate
over sequence of two notes, and apply \verb&PitchVP& to both note in the sequence.  The argument \verb&lambda l: l[0]-l[1]& is the \textit{function} expression, to be evaluated on every sequence of pitches.
The new viewpoint now appears in the list of viewpoints:

\lstinputlisting[firstline=28,lastline=28]{usecase_01_for_tex.py}


\begin{lstlisting}[backgroundcolor=\color{yellow}]
predefined viewpoints:
* DurationVP               	Note --> Duration: returns the duration of a note.
* PitchVP                  	Note --> Pitch: returns the pitch of a note.
* UserVP                   	A class to facilitate the creation of user-defined VP.

viepoint constructors:
* LinkedVP                 	[VP] --> VP: Takes a list of VP and returns a VP that applies 
                                         all VP in the list, returning a list of values

user-defined viewpoints:
* melodic interval         	[pitch, pitch] --> mi
\end{lstlisting}

And it can be applied:

\lstinputlisting[firstline=29,lastline=29]{usecase_01_for_tex.py}


\begin{center}
          \includegraphics[width=0.8\textwidth]{./screenshot3.eps}\\
\end{center}

Another example:


\lstinputlisting[firstline=31,lastline=34]{usecase_01_for_tex.py}

\begin{lstlisting}[backgroundcolor=\color{yellow}]
predefined viewpoints:
* DurationVP               	Note --> Duration: returns the duration of a note.
* PitchVP                  	Note --> Pitch: returns the pitch of a note.
* UserVP                   	A class to facilitate the creation of user-defined VP.

viepoint constructors:
* LinkedVP                 	[VP] --> VP: Takes a list of VP and returns a VP that applies 
                                         all VP in the list, returning a list of values

user-defined viewpoints:
* melodic interval         	[pitch, pitch] --> mi
* duration ratio           	[duration, duration] --> dr

\end{lstlisting}


\begin{center}
          \includegraphics[width=0.8\textwidth]{./screenshot4.eps}\\
\end{center}

Finally, using a predefined viewpoint constructor:


\lstinputlisting[firstline=36,lastline=39]{usecase_01_for_tex.py}


\begin{lstlisting}[backgroundcolor=\color{yellow}]
predefined viewpoints:
* DurationVP               	Note --> Duration: returns the duration of a note.
* PitchVP                  	Note --> Pitch: returns the pitch of a note.
* UserVP                   	A class to facilitate the creation of user-defined VP.

viepoint constructors:
* LinkedVP                 	[VP] --> VP: Takes a list of VP and returns a VP that applies 
                                         all VP in the list, returning a list of values

user-defined viewpoints:
* melodic interval         	[pitch, pitch] --> mi
* duration ratio           	[duration, duration] --> dr
* linked(mi,dr)            	[mi, dr]
\end{lstlisting}




\begin{center}
          \includegraphics[width=0.8\textwidth]{./screenshot5.eps}\\
\end{center}


\setlength{\parskip}{10pt}
\setlength{\parindent}{0pt}
\section{Implementation ideas}


The main design idea is to split the application of a viewpoint between two classes: \verb&Template& and \verb&VP&.

\subsection{Template}


The \verb&Template& class is responsible for iterating a \verb&music21& \verb&stream& (high-level container for musical material).  
The idea is that everything that relates to accessing \verb&music21& data should be delagated to a tempate (except perhaps basic
viewpoints like pitch and duration).


This is done by defining the standard
python methods to act as an iterator:


\hspace{.8\funcindent}\begin{boxedminipage}{\funcwidth}

    \raggedright \textbf{\_\_iter\_\_}(\textit{self})

\setlength{\parskip}{2ex}
\setlength{\parskip}{1ex}
    \end{boxedminipage}

    \label{templates:NoteTemplate:next}
    \index{templates \textit{(module)}!templates.NoteTemplate \textit{(class)}!templates.NoteTemplate.next \textit{(method)}}

    \vspace{0.5ex}

\hspace{.8\funcindent}\begin{boxedminipage}{\funcwidth}

    \raggedright \textbf{next}(\textit{self})

\setlength{\parskip}{2ex}
\setlength{\parskip}{1ex}
    \end{boxedminipage}


Every access to the iterator returns a musical ``structure'', which is
an iterator over features or other structures.  This is done to accomodate how the viewpoint methods can structure the
musical material of the corpus in many ways, i.e. sim/seq.  Using
templates is somehow more general as the structuring occurs on-the-fly
(defined by how \verb&music21& \verb&stream& object is iterated) and
there is no need for the highest-level structure to be a sequence.

The structure that a template returns is passed to
the viewpoint function, see next section.  The viewpoint function is
responsible to ``recurse'' into the structure and apply prerequisite
viewpoints (e.g. applying \verb&PitchVP& before computing melodic
interval). Perhaps this should be delagated to the \verb&Template&
class as well? Also, it might be a good idea to access previously
computed results if they exists.

Finally, the \verb&Template& class contains the following
\verb&stream& methods:

\hspace{.8\funcindent}\begin{boxedminipage}{\funcwidth}

    \raggedright \textbf{setStream}(\textit{self}, \textit{stream})

\setlength{\parskip}{2ex}
\setlength{\parskip}{1ex}
    \end{boxedminipage}

    \label{templates:Template:slice_stream}
    \index{templates \textit{(module)}!templates.Template \textit{(class)}!templates.Template.slice\_stream \textit{(method)}}

    \vspace{0.5ex}

\hspace{.8\funcindent}\begin{boxedminipage}{\funcwidth}

    \raggedright \textbf{sliceStream}(\textit{self}, \textit{stream}, \textit{slice\_})

\setlength{\parskip}{2ex}
\setlength{\parskip}{1ex}
    \end{boxedminipage}


The method \verb&setStream& simply aissgns the stream that the template is
currently processing.  This cannot be done when the object is created
as the same template might iterate over many different streams.

The method \verb&sliceStream& returns a ``reasonable'' slice on which
to demonstrate the application of a viewpoint. This is deferred to
\verb&Template& class as different templates might require to present
a different segment of the stream.

\subsection{VP}

The \verb&VP& class has two main methods: 

\hspace{.8\funcindent}\begin{boxedminipage}{\funcwidth}

    \raggedright \textbf{apply}(\textit{self}, \textit{stream})

\setlength{\parskip}{2ex}
\setlength{\parskip}{1ex}
    \end{boxedminipage}

\hspace{.8\funcindent}\begin{boxedminipage}{\funcwidth}

    \raggedright \textbf{vp\_function}(\textit{self}, \textit{structure\_iterator})

\setlength{\parskip}{2ex}
\setlength{\parskip}{1ex}
    \end{boxedminipage}


The method \verb&apply& iterates the stream using viewpoint's
predefined template:

\lstinputlisting[firstline=42,lastline=47]{../viewpoints.py}

Notice how the template acts as an iterator, it is simply used in the
\verb&for& loop. (note: the code above is actually delegated to a helper function)

The \verb&vpFunction& simply applies the viewpoint's function.  For
basic viewpoints like \verb&PitchVp&:


\lstinputlisting[firstline=102,lastline=103]{../viewpoints.py}

For the \verb&UserVP& class, this is more complex as the structure
needs to be iterated and prerequisite viewpoints to be applied:

\begin{lstlisting}
	def vpFunction(self,structure):
		# Before applying the function, apply other VPs to the structure
		# This returns an iterator of values.
		# The VP function is actually applied on this, not the structure of notes

		feature = self.function(ValueIterator_(self.template_expression,structure))
		feature.name = self.shortname
		return (structure[self.assign_index],feature)
\end{lstlisting}

Where \verb&ValueIterator_& is a helper class that applies the
prerequisite viewpoints specified in the template, hence transforming the
structure iterator (which iterates over notes) into an iterator over values.




\section{Progress and TODOs}

As it is, the code is more of a sketch and works minimally for the use
case presented above.
Also, the implementation design is not fixed, in particular w.r.t. how
features are encoded and how the results of applying a viewpoint a
stored (there is a dedicated class, but it is used as a normal dictionary/hash).

\subsection{Sketching a paper}

Perhaps the first thing to discuss is the content of an eventual
paper.  The code does not have to be complete for a paper to make
sense.  But if we present part of the implementation, then we should
agree on these parts and their design principles.

Also, should we focus on user-friendliness and perhaps include various
visualization functionalities or quickly go over viewpoints in the
paper and perhaps include data mining functionalities in the library.

\subsection{Template}
The \verb&Template& class still requires a lot of work.  It basically
works only for musical material structured as the chorales are (parts,
measures, notes).  The intend is that is should return
something reasonable for any \verb&music21& \verb&stream&.

Another idea of using a \verb&Template& class is that a lot of the
work of implemeting a new viewpoint can be reused by using an existing
template, i.e. if  typical templates are implemented (
sequences of notes, sequences of sims, etc.), then defining a new
viewpoint is really a matter of writing the appropriate function.

 Also, we might be able
to reuse parts of the iteration code of a template to create another
similar template.  In particular, we could have a template builder
that takes care of interpreting basic temporal constraints and
returning an iterator over groups of notes that satisfy those constraints.


\subsection{Features}

There is currently minimal implementation of feature operators, namely
``-'' over pitches and ``/'' over durations.

\subsection{Storing results}

The results of applying a viewpoint are currently stored in an
``informal'' fashion.  Do we want to make this more clear? With a class?

\subsection{Two -level API?}

A class such as \verb&UserVP& is probably not interesting to users.
It is too complex and does not really need to be extended.  We could
 have two viewpoints module: one with simpler viewpoints
that are meant to be used directly or extended via class inheritance,
and one with complex classes that are meant to be used as is.  Or
perhaps have \verb&UserVP& defined as a sort of constructor (even
though is does not take VPs as input).  Maybe a ``builder''.

The
same thing might be useful for templates as well, hiding the more
complex templates: e.g. a templates that iterate any stream and
returns notes that satisfy some set of temporal constraints.


\subsection{Feature sets, voices, variables}

Do we want to plan ahead and support voices? Variables? Feature sets?
(perhaps a general mechanism to store results, with some data mining
functionalities being applicable to feature sets, other to linked
viewpoints, etc.). 

\subsection{Testing and Coding style}

We needs a testsuite.  In particular to make sure that every reasonnable
\verb&music21& \verb&stream& is supported. Also, in my experience, it
is rather easy to break python code (a lot of ``checks'' are made
dynamically, so regions of code that are not tested can easily contain
bugs without one noticing).


Finally, the coding style of \verb&music21& uses a different convention
than the recommanded python style (e.g. \verb&usingCapsInFuncNames&
instead of \verb&using_underscores&).  Best to go with
\verb&music21&'s style in case it the viewpoints library gets
integrated into \verb&music21&.



\end{document}
